home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / ngeteblk.z / ngeteblk
Encoding:
Text File  |  2002-10-03  |  6.0 KB  |  132 lines
  1.  
  2.  
  3.  
  4. nnnnggggeeeetttteeeebbbbllllkkkk((((DDDD3333))))                                                      nnnnggggeeeetttteeeebbbbllllkkkk((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk - get an empty buffer of the specified size
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_bbbb_uuuu_ffff_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  15.      _bbbb_uuuu_ffff______tttt _****_nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk_((((_ssss_iiii_zzzz_eeee______tttt _b_s_i_z_e_))))_;;;;
  16.  
  17.    AAAArrrrgggguuuummmmeeeennnnttttssss
  18.      _b_s_i_z_e     Size of the buffer being requested.
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk retrieves a buffer [see _bbbb_uuuu_ffff(D4)] of size _b_s_i_z_e from the buffer
  22.      cache and returns a pointer to the buffer header.  If a buffer is not
  23.      available, _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk dynamically allocates one.  If memory is not
  24.      immediately available, _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk will sleep until enough memory has been
  25.      freed to allocate the buffer.
  26.  
  27.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  28.      A pointer to the buffer header structure is returned.
  29.  
  30. UUUUSSSSAAAAGGGGEEEE
  31.      When the driver _ssss_tttt_rrrr_aaaa_tttt_eeee_gggg_yyyy(D2) routine receives a buffer header from the
  32.      kernel, all the necessary members are already initialized.  However, when
  33.      a driver allocates buffers for its own use, it must set up some of the
  34.      members before calling its _ssss_tttt_rrrr_aaaa_tttt_eeee_gggg_yyyy routine.
  35.  
  36.      The following list describes the state of these members when the buffer
  37.      header is received from _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk:
  38.  
  39.           _bbbb______ffff_llll_aaaa_gggg_ssss       is set to indicate the transfer is from the user's
  40.                         buffer to the kernel.  The driver must set the _BBBB______RRRR_EEEE_AAAA_DDDD
  41.                         flag if the transfer is from the kernel to the user's
  42.                         buffer.
  43.  
  44.           _bbbb______eeee_dddd_eeee_vvvv        is set to _NNNN_OOOO_DDDD_EEEE_VVVV and must be initialized by the driver.
  45.  
  46.           _bbbb______bbbb_cccc_oooo_uuuu_nnnn_tttt      is set to _b_s_i_z_e.
  47.  
  48.           _bbbb______uuuu_nnnn_...._bbbb______aaaa_dddd_dddd_rrrr   is set to the buffer's virtual address.
  49.  
  50.           _bbbb______bbbb_llll_kkkk_nnnn_oooo       is not initialized by _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk, and must be
  51.                         initialized by the driver
  52.  
  53.      Typically, block drivers do not allocate buffers.  The buffer is
  54.      allocated by the kernel, and the associated buffer header is used as an
  55.      argument to the driver _ssss_tttt_rrrr_aaaa_tttt_eeee_gggg_yyyy routine.  However, to implement some
  56.      special features, such as _iiii_oooo_cccc_tttt_llll(D2) commands that perform I/O, the driver
  57.      may need its own buffer space.  The driver can get the buffer space from
  58.      the system by using _gggg_eeee_tttt_eeee_bbbb_llll_kkkk(D3) or _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk.  Or the driver can choose to
  59.      use its own memory for the buffer and only allocate a buffer header with
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. nnnnggggeeeetttteeeebbbbllllkkkk((((DDDD3333))))                                                      nnnnggggeeeetttteeeebbbbllllkkkk((((DDDD3333))))
  70.  
  71.  
  72.  
  73.      _gggg_eeee_tttt_rrrr_bbbb_uuuu_ffff(D3).
  74.  
  75.      Note that buffers allocated via _nnnn_gggg_eeee_tttt_eeee_bbbb_llll_kkkk must be freed using either
  76.      _bbbb_rrrr_eeee_llll_ssss_eeee(D3) or _bbbb_iiii_oooo_dddd_oooo_nnnn_eeee(D3).
  77.  
  78.    LLLLeeeevvvveeeellll
  79.      Base only.
  80.  
  81.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  82.      Can sleep.
  83.  
  84.      Driver-defined basic locks and read/write locks may not be held across
  85.      calls to this function.
  86.  
  87.      Driver-defined sleep locks may be held across calls to this function.
  88.  
  89. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  90.      _bbbb_iiii_oooo_dddd_oooo_nnnn_eeee(D3), _bbbb_rrrr_eeee_llll_ssss_eeee(D3), _bbbb_uuuu_ffff(D4), _gggg_eeee_tttt_eeee_bbbb_llll_kkkk(D3)
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.